Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 5 - Menu Manager Reference / Menu Manager Resources

The Menu Resource

CHANGED WITH THE APPEARANCE MANAGER

You can provide descriptions of your menus in 'MENU' resources and use the function GetMenu or GetNewMBar to read the descriptions of your menus. After reading in the resource description, the Menu Manager stores the information about specific menus in menu structures. When you use a menu resource to define a menu, you should check for the presence of an extended menu resource with the same resource ID.

WARNING

Menus in a resource must not be purgeable nor should they have the resource lock bit set. They must have resource ID numbers greater than 127. Do not define a "circular" hierarchical menu--that is, a hierarchical menu in which a submenu has a submenu whose submenu is a hierarchical menu higher in the chain.

Figure 5-1 shows the format of a compiled 'MENU' resource.

Figure 5-1 Structure of a compiled menu ('MENU') resource

A compiled version of a 'MENU' resource contains the following elements:

• Menu ID. Each menu in your application should have a unique menu ID (this can be the menu's resource ID). A negative value indicates that the menu (but not a submenu) belongs to a driver such as a desk accessory. A menu ID from 1 through 235 indicates a menu (or submenu) of an application; a menu ID from 236 through 255 indicates a submenu of a driver. Apple reserves the menu ID of 0.
• Placeholder (two integers containing 0) for the menu's width and height. After reading in the resource data, the Menu Manager requests the menu definition function to calculate the width and height of the menu and to store these values in the menuWidth and menuHeight fields of the menu structure.
• Resource ID of the menu's menu definition function; see "Menu Definition IDs". If the integer 63 appears here, as specified by the kMenuStdMenuProc constant in the Rez input file, the Menu Manager uses the standard Appearance-compliant menu definition function to manage the menu. If you provide your own menu definition function, its resource ID should appear in this field. After reading in the menu's resource data, the Menu Manager reads in the menu definition function, if necessary. The Menu Manager stores a handle to the menu definition function in the menuProc field of the menu structure.
• Placeholder (an integer containing 0).
• The initial enabled state of the menu and first 31 menu items. This is a 32-bit value, where bits 1-31 indicate if the corresponding menu item is disabled or enabled, and bit 0 indicates whether the menu as a whole is enabled or disabled. The Menu Manager automatically enables menu items greater than 31 when a menu is created.
• The length (in bytes) of the menu title.
• The title of the menu.
• Variable-length data that describes the menu items. If you provide your own menu definition function you can define and provide this data according to the needs of your function. The Menu Manager simply reads in the data for each menu item and stores it as variable data at the end of the menu structure. The menu definition function is responsible for interpreting the contents of the data. For example, the standard menu definition function interprets this data according to the description given in the following paragraphs.
• Placeholder (a byte containing 0) to indicate the end of the menu item definitions.

Figure 5-2 shows the variable-length data portion of a compiled 'MENU' resource that uses the standard menu definition function.

Figure 5-2 The variable-length data that describes menu items as defined by the standard menu definition function

The variable-length data portion of a compiled version of a 'MENU' resource that uses the standard menu definition function contains the following elements:

• Length (in bytes) of the menu item's text.
• Text of the menu item.
• A 1-byte field containing one of the following:
  • An icon number. The icon number is a number from 1 through 255 (or from 1 through 254 for small or reduced icons). The Menu Manager adds 256 to the icon number to generate the resource ID of the menu item's icon. If a menu item has an icon, you should also provide a 'cicn', 'SICN', or an 'ICON' resource with the resource ID equal to the icon number plus 256. If you want the Menu Manager to reduce an 'ICON' resource to the size of a small icon, you must also provide the value 0x1D in the keyboard equivalent field. If you provide a 'SICN' resource, provide 0x1E in the keyboard equivalent field. Otherwise, the Menu Manager looks first for a 'cicn' resource with the calculated resource ID and uses that icon.
  • A text encoding value. (Not recommended with Appearance.) If you want the Menu Manager to draw the item's text in a script other than the system script, specify the text encoding here and also provide 0x1C in the keyboard equivalent field. If the script system for the specified script is installed, the Menu Manager draws the item's text using that script.
  • 0 (as specified by the noicon constant in a Rez input file) if the menu item doesn't contain an icon and uses the system script.

    A menu item can have an icon or be drawn in a script other than the system script, but not both.

• Keyboard equivalent (specified as a 1-byte character). This can be enhanced with modifier key constants in the modifier keys field of the extended menu resource; see "The Extended Menu Resource". In some cases, this field may take on one of the following values instead:
  • 0x1B (as specified by the constant hierarchicalMenu in a Rez input file) if the item has a submenu. (Not recommended with Appearance.)
  • 0x1C if the item uses a script other than the system script. (Not recommended with Appearance.)
  • 0x1D if you want the Menu Manager to reduce an 'ICON' resource to the size of a small icon.
  • 0x1E if you want the Menu Manager to use an 'SICN' resource for the item's icon.
  • 0 (as specified by the nokey constant in a Rez input file) if the item has neither a keyboard equivalent nor a submenu and uses the system script.

    The values 0x01 through 0x1A as well as 0x1F and 0x20 are reserved for use by Apple; your application should not use any of these reserved values in this field.

• A 1-byte field containing one of the following:
  • A marking character. Special marking characters are available to indicate the marks associated with a menu item.
  • The menu ID of the item's submenu. (Not recommended with Appearance.) Submenus of an application should have menu IDs from 1 through 235; submenus of a driver (such as a desk accessory) should have menu IDs from 236 through 255. If you choose a submenu, you must also set the keyboard equivalent field to 0x1B.
  • 0 (as specified by the nomark constant in a Rez input file) if the item has neither a mark nor a submenu.

    A menu item can have a mark or a submenu, but not both.

• Font style of the menu item. The constants bold, italic, plain, outline, and shadow can be used in a Rez input file to define their corresponding styles.

If you provide your own menu definition function, you should use the same format for your resource descriptions of menus as shown in Figure 5-1. You can use the same format or one of your choosing to describe menu items. You can also use bits 1-31 of the enableFlags field of the menu structure as you choose; however, bit 0 must still indicate whether the menu is enabled or disabled.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

The menu resource, while identical in format, may take on different values in its variable-length data portion, depending on the type of information you want to display with your menu item.